% LaTeX source for 'Python: In Hydrology'
% Copyright (c)  2011  Sat Kumar Tomer

% Permission is granted to copy, distribute and/or modify this
% document under the terms of the GNU Free Documentation License,
% Version 1.1  or any later version published by the Free Software
% Foundation; with no Invariant Sections, no Front-Cover Texts,
% and no Back-Cover Texts.

% This distribution includes a file named fdl.tex that contains the text
% of the GNU Free Documentation License.  If it is missing, you can obtain
% it from www.gnu.org or by writing to the Free Software Foundation,
% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
%

% ACKNOWLEDGEMENT
% I am using the Latex file of Allen Downey
% which he used in the book, 'Think Python: How to Think Like a Computer Scientist'.

\documentclass[10pt]{book}
\usepackage[width=5.5in,height=8.5in,
  hmarginratio=3:2,vmarginratio=1:1]{geometry}

% for some of these packages, you might have to install
% texlive-latex-extra (in Ubuntu)

\usepackage{keyval}
\usepackage[procnames]{listings}
\usepackage{pslatex}
%\usepackage{url}
\usepackage{fancyhdr}
\usepackage{graphicx}
\usepackage{amsmath, amsthm, amssymb} 
\usepackage[pdfborder={0 0 0}]{hyperref} 
\usepackage{exercise}                        % texlive-latex-extra
\usepackage{makeidx}
\usepackage{setspace}
\usepackage{hevea}                           
\usepackage{upquote}
\usepackage{listings}
\usepackage{booktabs}
\usepackage{tikz}
\usepackage{wallpaper}
\usetikzlibrary{shapes,arrows}
\definecolor{myred}{cmyk}{0.1,1.0,0.6,0.2}
\definecolor{myblue}{cmyk}{1.0,0.5,0.0,0.60}
\usepackage{color}

\hypersetup{
  colorlinks = true,
  urlcolor = myblue,
  linkcolor = myblue,
  pdfauthor = {sat kumar},
  pdfkeywords = {hydrology, python},
  pdftitle = {Hydrology in Python by S. K. Tomer},
  pdfpagemode = UseNone
}

\definecolor{keywords}{RGB}{255,0,90}
\definecolor{comments}{RGB}{0,0,113}
\definecolor{red}{RGB}{160,0,0}
\definecolor{green}{RGB}{0,150,0}

\lstset{language=Python, 
        basicstyle=\ttfamily\small, 
        keywordstyle=\color{keywords},
        commentstyle=\color{comments},
        stringstyle=\color{red},
        showstringspaces=false,
        identifierstyle=\color{green},
        procnamekeys={def,class}}

\makeindex

\title{Python}
\newcommand{\thetitle}{Hydrology: In Python}
\newcommand{\theversion}{0.0.0}

% these styles get translated in CSS for the HTML version
\newstyle{a:link}{color:black;}
\newstyle{p+p}{margin-top:1em;margin-bottom:1em}
\newstyle{img}{border:0px}

% change the arrows
\setlinkstext
  {\imgsrc[ALT="Previous"]{back.png}}
  {\imgsrc[ALT="Up"]{up.png}}
  {\imgsrc[ALT="Next"]{next.png}}

\makeindex

\begin{document}
\ThisTileWallPaper{8.5in}{11in}{images/cover.png}

\frontmatter

% LATEXONLY

\input{latexonly}

\newtheorem{ex}{Exercise}[chapter]

\begin{latexonly}

\renewcommand{\blankpage}{\thispagestyle{empty} \quad \newpage}

%\blankpage
%\blankpage

% TITLE PAGES FOR LATEX VERSION

%-half title--------------------------------------------------
\thispagestyle{empty}

\begin{flushright}
\vspace*{2.0in}

%\begin{spacing}{3}
%{\Huge Python}\\
%{\Large In Hydrology}
%\end{spacing}

\vspace{0.25in}

%Version \theversion

\vfill

\end{flushright}

%--verso------------------------------------------------------

\blankpage
%\clearemptydoublepage
%\pagebreak
%\thispagestyle{empty}
%\vspace*{6in}

%--title page--------------------------------------------------
\pagebreak
\thispagestyle{empty}

\begin{flushright}
\vspace*{2.0in}

\begin{spacing}{3}
{\Huge Hydrology}\\
{\large In Python}
\end{spacing}

\vspace{0.25in}

Version \theversion

\vspace{1in}


{\huge Sat Kumar Tomer } \vspace{0.15in} \\ 



\vspace{0.5in}

\vfill
%{\Large Green Tea Press}

%{\small Needham, Massachusetts}

%\includegraphics[width=1in]{images/logo1.eps}


\end{flushright}


%--copyright--------------------------------------------------
\pagebreak
\thispagestyle{empty}

{\small
Copyright \copyright ~2011 Sat Kumar Tomer.


Printing history:

\begin{description}

\item[May 2013:] Started writing the book {\em Python in Hydrology}.
\end{description}

\vspace{0.2in}

\begin{flushleft}
Green Tea Press       \\
9 Washburn Ave \\
Needham MA 02492
\end{flushleft}

Permission is granted to copy, distribute, and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and with no Back-Cover Texts. \\

The GNU Free Documentation License is available from \url{www.gnu.org}
or by writing to the Free Software Foundation, Inc., 59 Temple Place,
Suite 330, Boston, MA 02111-1307, USA. \\ 

The book is originally in the form \LaTeX\ source code. 
A pdf (portable document format) or ps (post script) format can be obtained 
by compiling this \LaTeX\ source code. The latest \LaTeX\ source code for the 
book is available from svn repository hosted at google code 
\url{http://www.google.code/p/hydrology-in-python/}. 

\vspace{0.2in}

} % end small

\end{latexonly}


% HTMLONLY

\begin{htmlonly}

% TITLE PAGE FOR HTML VERSION

{\Large \thetitle}

{\large Sat Kumar Tomer} \\


Version \theversion

\setcounter{chapter}{-1}

\end{htmlonly}

\chapter{Preface}

\section*{History}

When I wrote the book, ``Python in Hydrology", I thought of writing two books. First one focusing mainly on Python by using the hydrological example, and the second one focus on hydrology by using the python language as a tool. Hence I thought of name as ``Python in Hydrology" and ``Hydrology in Python". \\

When I studied the subject, ``hydrology" during my master of engineering, it was taught in a very disconnected way. We used to solve the numerical problem as mathematical juggling and try to find some number which can be treated as a correct answer, but we (atleast I, as I should not speak on the behalf of the other students of my class) did not know the answer why are we doing it? All the processes of hydrology e.g. evapotranspiration, runoff, infiltration, routing etc. were presented in so disconnected way, that I can guarantee no one would do hydrology after such disconnected piece of hydrology given. It was like giving a puzzle where the target is to connect all the pieces together and make some toy or something that make some sense. And, each part of the disconnected piece was explained in much details, but no attention was giving on how to join them, and even it was not told that they should be joined to make some sense. Just to give one example, we were taught how to do baseflow separation,  we also learnt it and did baseflow separation without knowing what was baseflow. So in this book I will put more effort on joining the disconnected pieces (various hydrological processes) of puzzle (hydrology) together, and putting less effort on various way of modelling same process. \\

As I mentioned in the first book that I am scared of reading books, especially those having more than 200 pages. So I will keep this book within this limit. Also, I do not like much of the text in the book, 
and like to learn through examples and (numerical) experiments, and will try to put my ideas less and less and emphasis on the objectives and how to achieve them through some example. \\

I hope that you will find this book helpful and enjoyable. \\

\vfill


Sat Kumar Tomer \\
Toulouse, France\\

Sat Kumar Tomer is a Post-doctoral fellow in the Centre d'Etudes Spatiales de la BIOsphere (CESBIO), Toulouse, France. \\


\section*{Acknowledgements}

I am thankful to you for reading the book, and hope to receive feedback from you.

I am very much thankful to the people who sent me feedback for my first book, which encouraged me to write this book, otherwise this book would not have come. \\

I am thankful to Allen B. Downey who provided the latex source code of his books, 
which helped me in formatting the book in a better way. \\

I am thankful to the Free Software Foundation for developing the GNU Free Documentation License. \\

I am thankful to the \url{http://www.flickr.com/} for making images available under the Creative Common License (\url{http://creativecommons.org/licenses/by-nc-sa/3.0/}) \\

I am thankful to Green Tea Press. \\

I am thankful to my wife Yukti Gill, and friends Bhawi Panwar, Ganjendara Yadav, Himanshu Joshi, Shadi Davarian, and Shobhit Khatyan for their continuous support. \\

\section*{Suggestions/corrections}
If you have a suggestion or correction, you are more than welcome to drop an email at \url{satkumartomer@gmail.com}. \\


\normalsize

\clearemptydoublepage

% TABLE OF CONTENTS
\begin{latexonly}

\tableofcontents

\lstlistoflistings

\clearemptydoublepage

\end{latexonly}

% START THE BOOK
\mainmatter


\chapter{Introduction}
In this chapter, we will break down the hydrological cycle into various hydrological processes and subsequently into various chapter of this book. A brief note on how to make your python with all the required library ready is also presented. \\


\section{Hydrological processes}
In my opinion, hydrology is the study of movement of water on the earth. The movement of water is caused by the energy received from the sun. A typical hydrological cycle is shown in the figure \ref{hc1}, which you are well aware of. Now lets make it simple for the modelling purpose. The conceptual hydrological cycle is shown in the figure \ref{•}. Kindly note that the ocean and snow parts of the hydrological cycle are dropped off from this figure, as they are not covered in this book. Figure \ref{•} is redrawn into the figure \ref{•}, where each hydrological process is replaced by the name of the chapter in which it is discussed. \\

\index{hydrological processes}

\begin{figure}
\label{hc1}
\includegraphics[width=\textwidth]{images/hydrological_cycle1.jpg}
\caption{Various processes of the hydrological cycle. \emph{Image courtesy: Flickr. \url{http://flic.kr/p/amYXLP} }}
\end{figure}



Like everything is fair in love and war but only if you \textbf{won}, Similarly everything is right in hydrological modelling if you it is validated. The strength of the hydrological model lies in the variable against which it is being validated not in the variable it is accounting for. For example, there is a distributed hydrological model, which accounts for soil moisture, groundwater, baseflow, evaporation, transpiration, runoff etc. but is validated against only stream flow (routed runoff), then the model is good only for stream flow, and other output (or intermediate) variable can not be trusted. \\

There is no physical model in the hydrology. Usually the governing numerical (partial differential) equation are consisted of conservation of mass, momentum and energy. The equations for the momentum are empirical in hydrology, one such example is Darcy's law. \\

\section{Python}
Usually all the Linux/Unix system has basic Python installed by-default. If you are in
some other platform (Windows or Mac), or for some reason your Linux/Unix does not have 
a basic version of Python installed, you can use the instructions given below to install the 
basic version of the Python depending upon on your platform. \\
  
The basic version of Python contains minimal packages required to run the python. 
Usually additional packages are required to do the required tasks, specially for most 
of the hydrological applications, for whom the basic version of python is not enough, 
and additional packages are must. The next section will describe the installation 
procedure for required additional packages. Throughout the book, {\verb" $"} represents the Unix/Linux shell or window's command line. The installation of Python for the various operating system is done in the following ways:

\index{Install Python}

\subsection{Ubuntu/Debian}
In the Ubuntu/Debian, the Python is installed by running the usual installation command, i.e.:
\beforeverb
\begin{verbatim}
$ sudo apt-get install python
\end{verbatim}
\afterverb

\index{apt-get}

\subsection{Fedora}
On Fedora, the installation of the Python is performed by using the following command:
\beforeverb
\begin{verbatim}
$ sudo yum install python
\end{verbatim}
\afterverb

\index{yum}

\subsection{FreeBSD}
Python is installed on FreeBSD by running:
\beforeverb
\begin{verbatim}
$ sudo pkg_add install python
\end{verbatim}
\afterverb
\index{pkg_add}

The Linux user might be familiar with \verb"sudo". It allows user to run programs with the security privileges of root or administrator. Window user may ignore \verb"sudo", as they do not need to specify this. \\

\subsection{Windows}
For Windows users, the suitable version of Python can be downloaded 
from \url{http://www.python.org/getit/}. 
It provides a .msi file, which can be easily installed by double clicking on it. \\

\subsection{Mac OS}
Mac OS users also can download a suitable version of Python from 
\url{http://www.python.org/getit/} and install it.

\index{Fedora}
\index{Ubuntu/Debian}
\index{FreeBSD}
\index{Windows}
\index{Mac OS}

\section{Install Additional Packages}
Pip is a useful program to install additional packages in Python, which provides an 
easiest way to install additional packages. 
Before installing pip, \verb"distribute" should be installed. 
To do so, first we need to download \verb"Distribute", 
which is done by downloading \verb"distribute_setup.py" file from 
\url{http://python-distribute.org/distribute\_setup.py}, 
and running the following command:
\beforeverb
\begin{verbatim}
$ sudo python distribute_setup.py
\end{verbatim}
\afterverb
Note again for Windows users the \verb"sudo" is not needed, and you can use the command
without using it. \\

\index{Install additional packages}

Now download the \verb"get-pip.py" from 
\url{https://github.com/pypa/pip/raw/master/contrib/get-pip.py}, and run as root:
\beforeverb
\begin{verbatim}
$ sudo python get-pip.py
\end{verbatim}
\afterverb

Note, that the \verb"distribute_setup.py" and \verb"get-pip.py" should be in 
your current working directory while installing, otherwise give the full path of the file. If you do not get any error in this procedure, \verb"pip" should 
be ready to install new packages. The procedure to install packages is simple, let's say
we want to install package \verb"SomePackage", then we need to run the following command:
\beforeverb
\begin{verbatim}
$ sudo pip install SomePackage
\end{verbatim}
\afterverb

In hydrology, frequently used packages are \verb"Numpy", \verb"Scipy", \verb"xlrd", 
\verb"xlwt", and \verb"gdal", so we will install all of them at this stage. 
\beforeverb
\begin{verbatim}
$ sudo pip install Numpy
$ sudo pip install Scipy
$ sudo pip install xlrd
$ sudo pip install xlwt
$ sudo pip install gdal
$ sudo pip install ambhas
\end{verbatim}
\afterverb
These packages/libraries can be installed by specifying all packages name in one line, 
i.e. \verb"$ sudo pip install Numpy Scipy xlrd xlwt gdal". 
But, at this time it is better to install them in separate line, 
so that if you get some error, you can easily find out which package is giving error.  
The most common problem with \verb"pip" is that, it is not able to download 
library/package from internet. It happens mainly when you use some proxy to connect
to the internet. In that case, we can download the \verb"*.tar.gz" file of the library 
using internet browser, and then run the \verb"pip" in the following way:
\beforeverb
\begin{verbatim}
$ sudo pip install /path/to/*.tar.gz
\end{verbatim}
\afterverb
Windows user can download \verb"*.exe" or \verb"*.msi" file if available and then 
install by double clicking it. \\

If this also fails then, as a last option, you can download \verb"*.tar.gz" file 
and extract it. Then, go to the folder where you have extracted the file. 
There, you should see the \verb"setup.py" file. Now, run the following command:
\beforeverb
\begin{verbatim}
$ sudo python setup.py install 
\end{verbatim}
\afterverb
If you see any error in this, which could possibly arise because of non-availability
of some dependent package/library in your computer. 
You should read the \verb"README" file provided with the package, 
it can provide you details of required package/library, and how to install them. \\

The package/libraries are upgraded using the pip in the following way.
\beforeverb
\begin{verbatim}
$ sudo pip install --upgrade some_package
\end{verbatim}
\afterverb
\index{Upgrade packages}

Some packages are available through the software version and control system like subversion, Git, Mercurial etc. Lets install the \verb"ambhas" (\url{https://code.google.com/p/ambhas/}) library using the svn. First we need to install svn. The svn package for various platform is listed on the \url{http://subversion.apache.org/packages.html}. For Windows platform I use the TortoiseSVN (\url{http://tortoisesvn.net/}). First we need to checkout (download) the \verb"ambhas" library. In the shell you can do in the following way:
\beforeverb
\begin{verbatim}
$ svn checkout https://ambhas.googlecode.com/svn/trunk/ location_of_local_folder
\end{verbatim}
\afterverb
\index{svn}
After getting a copy of the \verb"ambhas", go to the \verb"location_of_local_folder", and you should see the \verb"setup.py" file. Then you can use this file to install the package.
\beforeverb
\begin{verbatim}
$ sudo python setup.py install
\end{verbatim}
\afterverb
\index{ambhas}

\section{Interactive Development Environment}
Simple text editors can be used to write Python programs, but these do not provide 
options for easy formatting of text, auto completion of text, and debugging options etc.  
IDE (Interactive Development Environment) provides many options to quickly format 
the program in Python way, and easily debug them. There are various IDE available 
for use e.g. PyDev, Spyder, IDLE, and many many others. A list of them can be 
found at \url{http://wiki.python.org/moin/IntegratedDevelopmentEnvironments}. 
I am using Spyder for my work, which is similar to MATLAB. The reason to use 
Spyder was since earlier I used to work on MATLAB, and Spyder is similar to it, 
so I found myself to be familiar with it. However, you can use any IDE, and after 
being familiar, it doesn't matter which one you use. 
\index{IDE}

\section{Execute the Python script}
You can either execute the python script directly from shell/command line, or by using the IDE. All the codes used in this book are given in the folder \emph{codes}, which is available through \verb"svn" at the \url{https://hydrology-in-python.googlecode.com/svn/trunk/}. \\

Let us write our first script to test if Python is working properly. The script is \verb"myscript.py".
\lstinputlisting[caption=myscript.py,frame=single]{codes/myscript.py}




By convention, Python scripts have names that end with {\tt .py}. Suppose, you have named you script as 
{\tt myscript.py}, and you want to execute it, in a shell, you would do:
\beforeverb
\begin{verbatim}
$ python myscript.py
\end{verbatim}
\afterverb
or, you can give your script executable permission and simply run the script. In this case, the first line of your script should be \verb" #!/usr/bin/env python".
The syntax to do is:
\beforeverb
\begin{verbatim}
$ chmod +x myscript.py
$ ./myscript.py
\end{verbatim}
\afterverb
\index{Execute}

In KDE's, the details of executing scripts are different.  
You can find instructions for your environment at the Python website \url{python.org}. \\


Working in interactive mode is convenient for testing small pieces of code because 
you can type and execute them immediately.  But for anything more than a few lines, 
you should save your code as a script so you can modify and execute it in the future. \\


preparing python
read previous book
install new package
pip
download *.gz and install
using svn and install

install useful packages
ambhas
xlrd
xlwt
scipy
numpy
gdal
datetime
matplotlib
basemap

\lstinputlisting[caption=sample.py,frame=single]{codes/sample.py}

\chapter{Precipitation}


\section{Rainfall gauges}
missing data

\lstinputlisting[firstline=10,caption=rainfall\_theis\_poly.py,frame=single]{codes/rainfall_theis_poly.py}

\begin{figure}
\label{rain_location_gauge}
\includegraphics[scale=0.5]{images/rain_location_gauge.png}
\caption{Location of the rainfall gauges}
\end{figure}

\begin{figure}
\label{rain_thiessen_rain}
\includegraphics[scale=0.5]{images/rain_thiessen_rain.png}
\caption{Interpolated rainfall using the Thiessen polygon. The location of gauges is also shown.}
\end{figure}

\lstinputlisting[firstline=10,caption=rainfall\_idw.py,frame=single]{codes/rainfall_idw.py}

\begin{figure}
\label{rain_thiessen_rain}
\includegraphics[scale=0.5]{images/rain_idw.png}
\caption{Interpolated rainfall using the IDW. The location of gauges is also shown.}
\end{figure}



\section{Satellite}
\section{GCM}
\section{Rescaling}


\chapter{Potential evapotranspiration}
\section{FAO}
\section{Priestley Taylor}
\section{Hargreaves}
\section{Makkink}
\section{Turc}

\chapter{Infiltration}
\chapter{Soil moisture}
\chapter{Groundwater}
\chapter{Surface runoff}
\chapter{Routing}
\chapter{Hydrological modelling}

\printindex
\end{document}
